ajaxForm
and ajaxSubmit
,
gather information from the form element to determine how to manage the submit process.
Both of these methods support
numerous options which allows you to have full control over how the data is submitted.
Submitting a form with AJAX doesn't get any easier than this!
<form id="myForm" action="comment.php" method="post">
Name: <input type="text" name="name" />
Comment: <textarea name="comment"></textarea>
<input type="submit" value="Submit Comment" />
</form>
<html>
<head>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7/jquery.js"></script>
<script src="https://malsup.github.io/jquery.form.js"></script>
<script>
// wait for the DOM to be loaded
$(document).ready(function() {
// bind 'myForm' and provide a simple callback function
$('#myForm').ajaxForm(function() {
alert("Thank you for your comment!");
});
});
</script>
</head>
...
That's it!
When this form is submitted the name and comment fields will be posted to comment.php. If the server returns a success status then the user will see a "Thank you" message.
ajaxForm
ajaxForm
in your document's ready
function to
prepare your form(s) for AJAX submission. ajaxForm
takes zero or one argument. The single argument
can be either a callback function or an Options Object.Note: You can pass any of the standard
$.ajax
options to ajaxForm
$('#myFormId').ajaxForm();
ajaxSubmit
ajaxSubmit
takes zero or one argument. The single argument
can be either a callback function or an Options Object.Note: You can pass any of the standard
$.ajax
options to ajaxSubmit
// attach handler to form's submit event
$('#myFormId').submit(function() {
// submit the form
$(this).ajaxSubmit();
// return false to prevent normal browser submit and page navigation
return false;
});
formSerialize
name1=value1&name2=value2
var queryString = $('#myFormId').formSerialize();
// the data could now be submitted using $.get, $.post, $.ajax, etc
$.post('myscript.php', queryString);
fieldSerialize
name1=value1&name2=value2
var queryString = $('#myFormId .specialFields').fieldSerialize();
fieldValue
// get the value of the password input
var value = $('#myFormId :password').fieldValue();
alert('The password is: ' + value[0]);
resetForm
$('#myFormId').resetForm();
clearForm
$('#myFormId').clearForm();
clearFields
$('#myFormId .specialFields').clearFields();
Note: Aside from the options listed below, you can also pass any of the standard
$.ajax
options to ajaxForm and ajaxSubmit.
ajaxForm
and ajaxSubmit
support
numerous options which can be provided using an Options Object. The Options Object is simply
a JavaScript object that contains properties with values set as follows:
Example:
// prepare Options Object
var options = {
target: '#divToUpdate',
url: 'comment.php',
success: function() {
alert('Thanks for your comment!');
}
};
// pass options to ajaxForm
$('#myForm').ajaxForm(options);
Note that the Options Object can also be used to pass values to jQuery's
$.ajax
method.
If you are familiar with the options supported by $.ajax
you may use them in the Options Object passed to ajaxForm
and
ajaxSubmit
.
ajaxForm
to bind the form and demonstrates how to use pre- and post-submit callbacks.
// prepare the form when the DOM is ready
$(document).ready(function() {
var options = {
target: '#output1', // target element(s) to be updated with server response
beforeSubmit: showRequest, // pre-submit callback
success: showResponse // post-submit callback
// other available options:
//url: url // override for form's 'action' attribute
//type: type // 'get' or 'post', override for form's 'method' attribute
//dataType: null // 'xml', 'script', or 'json' (expected server response type)
//clearForm: true // clear all form fields after successful submit
//resetForm: true // reset the form after successful submit
// $.ajax options can be used here too, for example:
//timeout: 3000
};
// bind form using 'ajaxForm'
$('#myForm1').ajaxForm(options);
});
// pre-submit callback
function showRequest(formData, jqForm, options) {
// formData is an array; here we use $.param to convert it to a string to display it
// but the form plugin does this for you automatically when it submits the data
var queryString = $.param(formData);
// jqForm is a jQuery object encapsulating the form element. To access the
// DOM element for the form do this:
// var formElement = jqForm[0];
alert('About to submit: \n\n' + queryString);
// here we could return false to prevent the form from being submitted;
// returning anything other than false will allow the form submit to continue
return true;
}
// post-submit callback
function showResponse(responseText, statusText, xhr, $form) {
// for normal html responses, the first argument to the success callback
// is the XMLHttpRequest object's responseText property
// if the ajaxForm method was passed an Options Object with the dataType
// property set to 'xml' then the first argument to the success callback
// is the XMLHttpRequest object's responseXML property
// if the ajaxForm method was passed an Options Object with the dataType
// property set to 'json' then the first argument to the success callback
// is the json data object returned by the server
alert('status: ' + statusText + '\n\nresponseText: \n' + responseText +
'\n\nThe output div should have already been updated with the responseText.');
}
ajaxSubmit
to submit the form.
// prepare the form when the DOM is ready
$(document).ready(function() {
var options = {
target: '#output2', // target element(s) to be updated with server response
beforeSubmit: showRequest, // pre-submit callback
success: showResponse // post-submit callback
// other available options:
//url: url // override for form's 'action' attribute
//type: type // 'get' or 'post', override for form's 'method' attribute
//dataType: null // 'xml', 'script', or 'json' (expected server response type)
//clearForm: true // clear all form fields after successful submit
//resetForm: true // reset the form after successful submit
// $.ajax options can be used here too, for example:
//timeout: 3000
};
// bind to the form's submit event
$('#myForm2').submit(function() {
// inside event callbacks 'this' is the DOM element so we first
// wrap it in a jQuery object and then invoke ajaxSubmit
$(this).ajaxSubmit(options);
// !!! Important !!!
// always return false to prevent standard browser submit and page navigation
return false;
});
});
// pre-submit callback
function showRequest(formData, jqForm, options) {
// formData is an array; here we use $.param to convert it to a string to display it
// but the form plugin does this for you automatically when it submits the data
var queryString = $.param(formData);
// jqForm is a jQuery object encapsulating the form element. To access the
// DOM element for the form do this:
// var formElement = jqForm[0];
alert('About to submit: \n\n' + queryString);
// here we could return false to prevent the form from being submitted;
// returning anything other than false will allow the form submit to continue
return true;
}
// post-submit callback
function showResponse(responseText, statusText, xhr, $form) {
// for normal html responses, the first argument to the success callback
// is the XMLHttpRequest object's responseText property
// if the ajaxSubmit method was passed an Options Object with the dataType
// property set to 'xml' then the first argument to the success callback
// is the XMLHttpRequest object's responseXML property
// if the ajaxSubmit method was passed an Options Object with the dataType
// property set to 'json' then the first argument to the success callback
// is the json data object returned by the server
alert('status: ' + statusText + '\n\nresponseText: \n' + responseText +
'\n\nThe output div should have already been updated with the responseText.');
}
beforeSubmit
option. If this
pre-submit callback returns false, the submit process is aborted.
The following login form is used for each of the examples that follow. Each example
will validate that both the username and password fields have been filled
in by the user.
Form Markup:
<form id="validationForm" action="dummy.php" method="post">
Username: <input type="text" name="username" />
Password: <input type="password" name="password" />
<input type="submit" value="Submit" />
</form>
First, we initialize the form and give it a beforeSubmit
callback function - this is the validation function.
// prepare the form when the DOM is ready
$(document).ready(function() {
// bind form using ajaxForm
$('#myForm2').ajaxForm( { beforeSubmit: validate } );
});
formData
Argumentfunction validate(formData, jqForm, options) {
// formData is an array of objects representing the name and value of each field
// that will be sent to the server; it takes the following form:
//
// [
// { name: username, value: valueOfUsernameInput },
// { name: password, value: valueOfPasswordInput }
// ]
//
// To validate, we can examine the contents of this array to see if the
// username and password fields have values. If either value evaluates
// to false then we return false from this method.
for (var i=0; i < formData.length; i++) {
if (!formData[i].value) {
alert('Please enter a value for both Username and Password');
return false;
}
}
alert('Both fields contain values.');
}
jqForm
Argumentfunction validate(formData, jqForm, options) {
// jqForm is a jQuery object which wraps the form DOM element
//
// To validate, we can access the DOM elements directly and return true
// only if the values of both the username and password fields evaluate
// to true
var form = jqForm[0];
if (!form.username.value || !form.password.value) {
alert('Please enter a value for both Username and Password');
return false;
}
alert('Both fields contain values.');
}
fieldValue
Methodfunction validate(formData, jqForm, options) {
// fieldValue is a Form Plugin method that can be invoked to find the
// current value of a field
//
// To validate, we can capture the values of both the username and password
// fields and return true only if both evaluate to true
var usernameValue = $('input[name=username]').fieldValue();
var passwordValue = $('input[name=password]').fieldValue();
// usernameValue and passwordValue are arrays but we can do simple
// "not" tests to see if the arrays are empty
if (!usernameValue[0] || !passwordValue[0]) {
alert('Please enter a value for both Username and Password');
return false;
}
alert('Both fields contain values.');
}
<form id="jsonForm" action="json-echo.php" method="post">
Message: <input type="text" name="message" value="Hello JSON" />
<input type="submit" value="Echo as JSON" />
</form>
json-echo.php
:
<?php echo '{ "message": "' . $_POST['message'] . '" }'; ?>
JavaScript:
// prepare the form when the DOM is ready
$(document).ready(function() {
// bind form using ajaxForm
$('#jsonForm').ajaxForm({
// dataType identifies the expected content type of the server response
dataType: 'json',
// success identifies the function to invoke when the server response
// has been received
success: processJson
});
});
Callback function
function processJson(data) {
// 'data' is the json object returned from the server
alert(data.message);
}
<form id="xmlForm" action="xml-echo.php" method="post">
Message: <input type="text" name="message" value="Hello XML" />
<input type="submit" value="Echo as XML" />
</form>
xml-echo.php
:
<?php
// !!! IMPORTANT !!! - the server must set the content type to XML
header('Content-type: text/xml');
echo '<root><message>' . $_POST['message'] . '</message></root>';
?>
JavaScript:
// prepare the form when the DOM is ready
$(document).ready(function() {
// bind form using ajaxForm
$('#xmlForm').ajaxForm({
// dataType identifies the expected content type of the server response
dataType: 'xml',
// success identifies the function to invoke when the server response
// has been received
success: processXml
});
});
Callback function
function processXml(responseXML) {
// 'responseXML' is the XML document returned by the server; we use
// jQuery to extract the content of the message node from the XML doc
var message = $('message', responseXML).text();
alert(message);
}
htmlExampleTarget
div below.
<form id="htmlForm" action="html-echo.php" method="post">
Message: <input type="text" name="message" value="Hello HTML" />
<input type="submit" value="Echo as HTML" />
</form>
html-echo.php
:
<?php
echo '<div style="background-color:#ffa; padding:20px">' . $_POST['message'] . '</div>';
?>
JavaScript:
// prepare the form when the DOM is ready
$(document).ready(function() {
// bind form using ajaxForm
$('#htmlForm').ajaxForm({
// target identifies the element(s) to update with the server response
target: '#htmlExampleTarget',
// success identifies the function to invoke when the server response
// has been received; here we apply a fade-in effect to the new content
success: function() {
$('#htmlExampleTarget').fadeIn('slow');
}
});
});
This page demonstrates the Form Plugin's file upload capabilities. There is no special coding required to handle file uploads. File input elements are automatically detected and processed for you.
Browsers that support the XMLHttpRequest Level 2 will be able to upload files seamlessly and even get progress updates as the upload proceeds. For older browsers, a fallback technology is used which involves iframes since it is not possible to upload files using the level 1 implmenentation of the XMLHttpRequest object. This is a common fallback technique, but it has inherent limitations. The iframe element is used as the target of the form's submit operation which means that the server response is written to the iframe. This is fine if the response type is HTML or XML, but doesn't work as well if the response type is script or JSON, both of which often contain characters that need to be repesented using entity references when found in HTML markup.
To account for the challenges of script and JSON responses when using the iframe mode, the Form Plugin allows these responses
to be embedded in a textarea
element and it is recommended that you
do so for these response types when used in conjuction with file uploads and older browsers.
It is important to note that even when the dataType option is set to 'script', and the server is
actually responding with some javascript to a multipart form submission,
the response's Content-Type header should be forced to text/html
, otherwise Internet
Explorer will prompt the user to download a "file".
Also note that if there is no file input in the form then the request uses normal
XHR to submit the form (not an iframe). This puts the burden on your server code to know when
to use a textarea and when not to. If you like, you can use the iframe
option of the plugin to force it to always use an iframe mode and then your server can
always embed the response in a textarea. But the recommended solution is to test for the
'X-Requested-With' request header. If the value of that header is 'XMLHttpRequest' then you
know that the form was posted via ajax.
The following PHP snippet shows how you can be sure to return content successfully:
<?php
$xhr = $_SERVER['HTTP_X_REQUESTED_WITH'] == 'XMLHttpRequest';
if (!$xhr)
echo '<textarea>';
?>
// main content of response here
<?php
if (!$xhr)
echo '</textarea>';
?>
The form below provides an input element of type "file" along with a select element
to specify the dataType of the response. The form is submitted to
files.php
which uses the dataType to
determine what type of response to return.
Examples that show how to display upload progress:
fieldValue
and
fieldSerialize
methods.
fieldValue
allows you to retrieve the current value of a field. For example, to retrieve the value of the password
field in a form with the id of 'myForm' you would write:
var pwd = $('#myForm :password').fieldValue()[0];
This method always returns an array. If no valid value can be determined the
array will be empty, otherwise it will contain one or more values.
fieldSerialize
allows you to serialize a subset of a form into a
query string. This is useful when you need to process only certain fields. For example,
to serialize only the text inputs of a form you would write:
var queryString = $('#myForm :text').fieldSerialize();
fieldValue
and fieldSerialize
only function on
'successful controls'. This means that if you run the following code on a checkbox that is not checked, the result will
be an empty array.
// value will be an empty array if checkbox is not checked:
var value = $('#myUncheckedCheckbox').fieldValue();
// value.length == 0
However, if you really want to know the 'value' of the checkbox element, even if it's unchecked, you can
write this:
// value will hold the checkbox value even if it's not checked:
var value = $('#myUncheckedCheckbox').fieldValue(false);
// value.length == 1
ajaxForm
provides the simplest way to enable your HTML form to use AJAX. It's the one-stop-shopping
method for preparing forms.ajaxForm
and ajaxSubmit
?ajaxSubmit
submits the form, ajaxForm
does not. When you invoke ajaxSubmit
it immediately serializes the
form data and sends it to the server. When you invoke ajaxForm
it adds the necessary event listeners to the form
so that it can detect when the form is submitted by the user. When this occurs ajaxSubmit
is called for you.
ajaxForm
the submitted data will include the name and value of the submitting element (or its click coordinates if the
submitting element is an image).The Official Form Plugin is available here: jquery.form.js or from the plugin's Github repository.
Minified version: jquery.form.min.js There are many other useful Form Plugins available from the jQuery Plugins page.Development of the Form Plugin was a community effort with many people contributing ideas and code. The following people have made contributions of one kind or another:
Send me an email if I've forgotten someone.